REST URL

The REST URL is formed of the URL for the ebs web service and is stored on the ebs Application Server. The web service URL is located in the Web service host URL institution setting on the General (Cross-System) screen in ebs: central.

Web service host URL institution setting

REST uses this same URL with a /rest/ suffix at the end. For example: the enrolments web service would require a suffix of /rest/enrolments at the end of the web service host URL.

When creating or updating records in ebs, the created_by and updated_by fields in the table being updated will be changed according to the user who made the change, with the created_date and updated_date matching the system date of when the record was created or updated.

REST uses the following components and responses:

REST uses a set of verbs that enable you to add, delete and modify data in ebs. There are several verbs that can be used, but there are five key verbs which are predominantly used by ebs:

  • GET - retrieves data in ebs
  • POST - adds new data into ebs
  • PUT - updates existing data in ebs
  • DELETE - removes existing data from ebs
  • OPTIONS - queries information about the web service URL

Back to top

When browsers make requests they send headers. These headers tell the web service different information about what is being sent to the web service and what the web service will send back.

The key headers for ebs REST are:

  • Authorization – the login details of the user logging into the system
  • Content-type – the type of code being sent to the web service which will either be text/xml or text/json, depending on the code used in the Body
  • Accept – how the information will be returned which will usually be text/xml for ebs web services

Back to top

After running a query using web services, you will receive a response from the service informing you whether the query was successful or not, along with a body of text with either the results of the query or a reason why the query failed. Below is a list of common service responses you may encounter:

  • 200 – Query successful
  • 404 – The service has not found anything matching the request
  • 401 – The authentication token is either not in the Authorization header, is an invalid format or has expired
  • 403 – The ebs4 web services licence is not present or has expired
  • 400 – Either the raw format of the message is incorrect (e.g. unclosed XML tags) or the message or the operation has failed validation (in which case there should be an error report in the response body)
  • 405 – The HTTP verb you are using to invoke the service is not valid with the web service
  • 406 – The Content-Type or Accept header is populated with an unsupported media type (currently application/json and text/xml are supported)
  • 415 – The message supplied is in an unsupported format
  • 500 – An unhandled exception was thrown, check the log4net logs

Back to top